The Mule Jmx agent enables the configuration of a local or remote Jmx connection to Mule and registers Mule resources with the MBean server. With Jmx enabled you can do the following against a local or remote instance -

• View the configuration state of the MuleManager
• Stop and start the Mule instance.
• Stop and start the model.
• Stop, start, pause and resume components.
• Query event processing and endpoint routing stats on individual components or for the whole server instance.

To configure the agent with Mule use the following configuration -

<agents>
    <agent name="JmxAgent" className="org.mule.management.agents.JmxAgent"/>
</agents>

You can set the following properties on the agent.

Remote Management

It's also possible to configure the Mule JMX subsystem for remote management with 3rd-party tools like MC4J:

<agents>
    <!-- starts an RMI registry on the default port 1099. -->
    <agent name="RMI" className="org.mule.management.agents.RmiRegistryAgent"/>
    <agent name="JMX" className="org.mule.management.agents.JmxAgent">
        <properties>
            <property name="connectorServerUrl" value="service:jmx:rmi:///jndi/rmi://localhost:1099/server"/>
            <map name="connectorServerProperties">
                <property name="jmx.remote.jndi.rebind" value="true"/>
            </map>
        </properties>
    </agent>
<agents>

 Running an External RMI Server

If you are using JDK1.4 and running the RMI Registry externally using rmiregistry.exe (Bundled with JDK 1.4) you will need to add the JMX remoting Jar to your JDK classpath in order for the external RMI registry to serve Remote JMX clients.

This isn't an issue if running with JDK 1.5 as the JMX remoting classes are now part of the JDK.

Jmx Adapter Agents

In addition to the JmxAgent you can configure other agents to configure Jmx Adaptors or register supporting MBeans. Mule currently ships with two Jmx Adaptor agents: Mx4j and Jdmk.

Mx4j Configuration

To configure Mule to use the Mx4j Html Adaptor -

<agents>
    <agent name="JmxAgent" className="org.mule.management.agents.JmxAgent"/>
    <agent name="Mx4jAgent" className="org.mule.management.agents.Mx4jAgent">
        <properties>
            <property name="jmxAdaptorUrl" value="http://localhost:9999"/>
        </properties>
    </agent>
</agents>

http://localhost:9999 is the default URL and can be ommitted if there's no need to change it.

For security's sake, the management console is only accesible from the localhost. If you wish to loosen this restriction, change "localhost" to "0.0.0.0". This will allow access from any machine in the LAN. Refer to the MX4J docs for more details.

Mx4j Security

As of Mule 1.3 it is possible to protect the JMX web console with a login and password. If the login property has been specified, the protection scheme kicks in:

<agents>
        <agent name="jmxAgent"  className="org.mule.management.agents.JmxAgent"/>
        <agent name="mx4jAgent" className="org.mule.management.agents.Mx4jAgent">
            <properties>
                <property name="login" value="user"/>
                <property name="password" value="password"/>
            </properties>
        </agent>
    </agents>

By default, the BASIC authentication scheme is used.

As of Mule 1.3 SSL protection is also available:

<agents>
        <agent name="jmxAgent"  className="org.mule.management.agents.JmxAgent"/>
        <agent name="mx4jAgent" className="org.mule.management.agents.Mx4jAgent">
            <properties>
                <map name="socketFactoryProperties">
                    <property name="keyStoreName" value="serverKeystore"/>
                    <property name="keyStorePassword" value="mulepassword"/>
                </map>
            </properties>
        </agent>
    </agents>

The above config protects the data in transit, while still allowing anybody to access the console. It is recommended both approaches are combined for tighter control over the environment.

If socketFactoryProperties contains at least one entry, the agent will switch to HTTPS connections.

The jmxAdaptorUrl scheme is not important here, the choice of either HTTP or HTTPS will be made based on the availability of the socketFactoryProperties map. If this config is omitted, it will always use HTTP, even if you specify https:// connection scheme in the jmxAdaptorUrl property.

Property Name	Description	Required	Default Value
authenticationMethod	Method used to authenticate when login/password is available (since Mule 1.3)		BASIC
jmxAdaptorUrl	URL to expose web console at		http://localhost:9999
name	Name of this JmxAgent
login	Used to authenticate access (since Mule 1.3)
password	Used if login has been provided, can be empty (since Mule 1.3)
cacheXsl	Indicates whether to cache the transformation objects. This speeds-up the process. It is usually set to true, but you can set it to false for easier testing (since Mule 1.3)		true
xslFilePath	Used to customize adaptor's stylesheet. Determines where to look for xsl files. If the target file is a dir, it assumes that xsl files are located in the dir. Otherwise if it points to a .jar or .zip files, it assumes that the files are located inside. Pointing it to a file system is especially useful for testing (since Mule 1.3)
pathInJar	Used to customize adaptor's stylesheet. Sets the dir in the jar file where xsl files reside (since Mule 1.3)	(if xslFilePath points to a jar/zip)
socketFactoryProperties	A map containing properties for SSL server socket factory configuration. These will be delegated as is to the agent's HTTP/S adaptor. See mx4j API docs for the list of available properties.	(for HTTPS connections only)

Jdmk Configuration

To configure Mule to use the Jdmk Html Adaptor -

<agents>
    <agent name="JmxAgent" className="org.mule.management.agents.JmxAgent"/>
    <agent name="JdmkAgent" className="org.mule.management.agents.JdmkAgent">
        <properties>
            <property name="jmxAdaptorUrl" value="http://localhost:9998"/>
        </properties>
    </agent>
</agents>

 Viewing Statistics

Mule traps many different statistics about the running state of a server and number of events processed. With the Jdmk Html adaptor you can view the Mule statistics html report. To view the statistics report shown below using the above configuration go to the following url -

http://localhost:9998/InvokeAction//Mule%3Atype%3Dstatistics/action=
printHtmlSummary?action=printHtmlSummary

or from the Jmx console homepage -

http://localhost:9998 -> 'Mule:type=statistics' -> 'printHtmlSummary'

Cannot resolve external resource into attachment.
 

Other Management Agents

Log4J Agent

The log4j Agent exposes the configuration of the Log4J instance used by Mule for Jmx management.

<agents>
    <agent name="JmxAgent" className="org.mule.management.agents.JmxAgent"/>
    <agent name="Log4jAgent" className="org.mule.management.agents.Log4jAgent"/>
</agents>

All Jmx Agents can be used together if desired and you can register your own custom ones as well. Just ensure the org.mule.management.agents.JmxAgent is registered.

Default JMX Support Agent

You can configure all Jmx Agents with a single class called DefaultJmxSupportAgent. It will register your Mule instance with the following agents -

• Rmi agent (if necessary) on rmi://localhost:1099
• Jmx Registration agent
• Remote Jmx access on service:jmx:rmi:///jndi/rmi://localhost:1099/server
• Jmx Notification agent used to receive Server notifications using Jmx Notifications
• Log4J Jmx Agent
• (Optional) JDMK Agent - set loadJdmkAgent property to true (@since Mule 1.3.1)
• (Optional) MX4J Agent - set loadMx4jAgent property to true (@since Mule 1.3.1)

Just add the following to your configuration -

<agent name="JMX" className="org.mule.management.agents.DefaultJmxSupportAgent"/>

The agent does a lot of useful plumbing for JMX, however at the expense of defaulting many parameters. If you find a need to customize some subsystems you could either:

1. Subclass DefaultJmxSupportAgent and override corresponding createXXX() factory methods.
2. Disassemble the services provided by this support agent into separate agents and configure them individually.